.\"
.\"
.TH DYNAMO 1 "Dynamo" "25 July 2011" ""
.SH NAME
dynamo - Ada Web Application Generator
.SH SYNOPSIS
.B dynamo
[ -o
.I directory
] [ -t
.I templates
] [ -c
.I config-dir
]
.I command
.br
.SH DESCRIPTION
\fIdynamo\fR is a command to help developers write an Ada Web Application using the
.B ASF
framework.  \fIdynamo\fR provides several commands to perform one specific task in
the development process.
.\"
.PP
First the
.B create-project
command will be used to initiate a new project.  The project name is used at this stage
to configure the name of the root Ada package for the application.
.\""
.PP
The
.B add-model
command will be used to create a database table mapping file.  The database mapping file
describes how to map a database table into an Ada record type for the
.B ADO
framework.  The
.B generate
command is then used to build the Ada model files from the database mapping files.
At the same time, it generate the SQL database creation schemas for MySQL and SQLite databases.
.PP
The
.B add-page
command is then used to add web pages for the application.  When a new application
layout is necessary, the
.B add-layout
command can be used.
.\"
.PP
.I dynamo
uses the
.B dynamo.xml
file to get information on the project and customize the generation.  It scans the
GNAT project files to obtain the dependencies between several
.I dynamo
components.
.\"
.SH OPTIONS
The following options are recognized by \fIdynamo\fR:
.TP 5
-o directory
.br
Specifies the directory where result files are created.  The default is the current directory.
.TP 5
-c directory
.br
Specifies the configuration directory which contains \fIdynamo\fR configuration
files as well as template files.
.TP 5
-t directory
.br
Specifies the templates directory.  This option can be used to override the
templates provided by \fIdynamo\fR.
.\"
.SH COMMANDS
.\"
.SS The create-project command
.RS 0
dynamo \fBcreate-project \fIname\fR\fR
.RE
.PP
Create a new project in the current working directory or in the
directory specified by the
.I -o
option.  The project name should be a valid Ada identifier.  It represents the Ada root
package name for the project.  The command creates a set of Ada files, a configure script,
a Makefile as well as a
.I gnatmake
build file.  The application can be immediately compiled to obtain a web server that is ready
to run.
.\"
.SS The create-database command
.RS 0
dynamo \fBcreate-database \fImodel [connection] admin-user [admin-password]\fR\fR
.RE
.PP
The create-database command creates the database used by the application.
The database schema file is stored in the directory identified by
.I model
and is generated by the
.I generate
command.
The database connection string is optional.  The default database connection string
is read from the
.I database
property in the
.B dynamo.xml
configuration file.  The connection string has the following form: 
.\"
.RS 0
\fIdriver\fR://\fIhost\fR:\fIport\fR/\fIdatabase\fR
.RE
.PP
The command will connect to the database server specified by the connection string.
It will use the admin user for this connection. The database is created if it does
not yet exist. If a user is specified in the connection string, a grant command is
issued to create that user and allow him to access the new database.
.PP
The database tables are created by using the
.I create-name-driver.sql
script where
.I name
represents the Dynamo project name.
.\"
.SS The add-layout command
.RS 0
dynamo \fBadd-layout \fIname\fR\fR
.RE
.PP
Create a new XHTML layout file.  The layout file is an XHTML facelet template which can
be used by a web page to provide a common presentation layout.  When the project is
created, at least one layout is proposed.  By adding a new layout, the application
can provide different presentation styles.  The layout files are stored in the
.B web/WEB-INF/layouts
directory.
.\"
.\"
.SS The add-page command
.RS 0
dynamo \fBadd-page \fIname\fR\fR
.RE
.PP
Create a new presentation page.  The presentation page is an XHTML facelet file
which contains HTML code as well as ASF facelet components.  The presentation
pages are stored in the
.B web
directory.
.\"
.\"
.SS The add-model command
.RS 0
dynamo \fBadd-model [\fImodule\fR] \fIname\fR\fR
.RE
.PP
Create a new database table model mapping.  The model mapping is an XML file that
describes how to map a database table into an Ada type.
The model mappings are stored in the
.B db
directory.  The database table is mapped to an Ada tagged record in the package
\fB\fIproject-name\fR\fR.\fImodule\fR.Model\fR if a module name is passed otherwise the package
will have the name \fB\fIproject-name\fR.Model\fR.  The Ada record will have the name
\fB\fIname\fR_Ref\fR.
.\"
.SS The add-module command
.RS 0
dynamo \fBadd-module \fIname\fR\fR
.RE
.PP
Add a new module to the project.  The module is composed of a set of Ada files
and a set of XHTML presentation files.  The
.I name
parameter is the name of the Ada child package that represents the module.
This is also the name of the directory that will contain the specific XHTML files
used for the module.
The following Ada packages are generated:
.\"
.RS 0
package \fIproject\fR.\fImodule\fR;
.br
package \fIproject\fR.\fImodule\fR.Beans;
.br
package \fIproject\fR.\fImodule\fR.Module;
.RE
.PP
where
.I project
is the project name (defined by the
.B create-project
command) and
.I module
is the new module name.
.PP
The
.I Module
package defines the main module data type with the initialization steps.
The
.I Beans
package defines the Ada bean types which are specific to the module.
Each Ada bean type must be registered in the
.I Module
package.  The generated files are intended to be modified to implement the
module functionality.
.\"
.SS The info command
.RS 0
dynamo \fBinfo\fR
.RE
.PP
Report information about the current project.  This command scans the GNAT projects to
find the
.I dynamo
components dependencies.  It then lists the GNAT projects and the
.I dynamo
components that are used by the current project.
.\"
.SS The help command
.RS 0
dynamo \fBhelp \fIname\fR\fR
.RE
.PP
Give an help description about a command.
.\"
.SS The generate command
.RS 0
dynamo \fBgenerate [\fImodel ... \fR]\fR
.RE
.PP
Generate the Ada model implementation from the XML model mappings.
The Ada model files are generated in the
.B src/model
directory.  Developers should not modify those files by themselves.
When no file is specified, the
.B generate
command will read all the XML files stored in the
.B db
directory.  It will generate all the models found in those files.
.PP
At the same time, the command generates the SQL files to create the
database tables for the supported drivers (MySQL and SQLite).
For each project, it generates a set of SQL files that can be used
to create or delete the database tables.
.\"
.SS The propset command
.RS 0
dynamo \fBpropset \fIname value\fR\fR
.RE
.PP
Set a project property to configure some commands provided by
\fBdynamo\fR.  The property is composed of a name and a value.  It is saved in
the
.B dynamo.xml
file.  The following properties are recognized:
.\"
.\"
.SH PROPERTIES
The
.B dynamo.xml
file defines several configuration properties which are used to customize several
commands.  These properties can be modified with the
.B propset
command.
.\"
.SS author
This property defines the author name inserted in file headers.
.\"
.SS author_email
The author email address inserted in file headers.
.SS license
This property controls the license header in file headers.
The following license names are recognized:
.B gpl
.B apache
.\"
.SS database
The default database connection string.
.\"
.SH FILES
.SS /usr/share/dynamo/base/generator.properties
This configuration file is read by
.I dynamo
to configure various installation parameters necessary for the generation.
.\"
.SS /usr/share/dynamo/base/AdaMappings.xml
This XML file defines the type mapping used in the
.I dynamo
model files.  This mapping indicates for each basic type used in the
XML model files, what is the target Ada type name.
.\"
.SS /usr/share/dynamo/base/commands
This directory contains XML files that describe additional template commands.
.\"
.SS /usr/share/dynamo/base/templates
This directory contains the template files associated with
.I dynamo
commands.
.\"
.SH SEE ALSO
\fIgnatmake(1)\fR, \fIgcc(1)\fR
.\"
.SH COPYRIGHT
Copyright 2011 by Stephane Carrez.
.\"
